McBasic™ 0.7.881 · Build 881 · 11 min read

Controls · Visual control

ListBox

Keep a list selection and its output synchronized.

47 properties18 events1 methodsDefault: SelectionChanged

Build the ListBox lesson Properties Events Methods

Use it in a Form#

A ListBox keeps alternatives visible. Its Change handler should read the selected state, not infer it from the mouse position. Check initial and empty selection states so code does not index into an item that does not exist.

Add ListBox to its intended parent and name it lstChoice for this example:

Property	Example value
`Items`	`"First choice\nSecond choice\nThird choice"`
`SelectionMode`	`"Multiple"`
`Sorted`	`True`
`Padding`	`"8,6,8,6"`
`BorderStyle`	`"Solid"`
`BorderColor`	`"#5B6F92"`
`BorderWidth`	`2`
`CornerRadius`	`6`
`HorizontalScrollBar`	`"Auto"`
`VerticalScrollBar`	`"Auto"`
`SelectedIndex`	`0`

A complete handler from Forms/frmMain.bas. The linked lesson includes its surrounding controls, declarations and helpers.

Forms/frmMain.bas

Private Sub lstChoice_Change()
    Dim itemList As Collection
    Dim selectedItems As Collection
    Dim selectedIndices As Collection
    Dim selected As Variant
    Set itemList = lstChoice.Items
    Set selectedItems = lstChoice.SelectedItems
    Set selectedIndices = lstChoice.SelectedIndices
    selected = lstChoice.SelectedItem
    If lstChoice.SelectedIndex >= 0 Then
        lblStatus.Caption = CStr(lstChoice.SelectedCount) & " selected in " & lstChoice.SelectionMode & " mode at " & CStr(selectedIndices.Item(1))
    Else
        lblStatus.Caption = "No item is selected."
    End If
End Sub

Properties#

Contract defaults are shown below. Where a new control has a different Designer starting value, that value is listed separately.

`Left`

DoubleDefault: 0

Horizontal position in device-independent points, relative to the parent container.

Range: -100000 to 100000.

`Top`

DoubleDefault: 0

Vertical position in device-independent points, relative to the parent container.

Range: -100000 to 100000.

`Width`

DoubleDefault: 220

Control width in device-independent points.

Range: 0 to 100000.

`Height`

DoubleDefault: 120

Control height in device-independent points.

Range: 0 to 100000.

`MinWidth`

DoubleDefault: 0

Minimum control width in device-independent points; 0 lets the parent layout choose.

Range: 0 to 100000.

`MinHeight`

DoubleDefault: 0

Minimum control height in device-independent points; 0 lets the parent layout choose.

Range: 0 to 100000.

`MaxWidth`

DoubleDefault: 100000

Maximum control width in device-independent points.

Range: 0 to 100000.

`MaxHeight`

DoubleDefault: 100000

Maximum control height in device-independent points.

Range: 0 to 100000.

`TabIndex`

LongDefault: 0

Keyboard navigation order within the parent container; lower values come first.

Range: 0 to 100000.

`TabStop`

BooleanDefault: True

Whether Tab navigation can move focus to this ListBox.

`ZIndex`

LongDefault: 0

Stacking order among sibling controls; larger values appear in front. Equal values preserve document order.

Range: -100000 to 100000.

`Anchor`

StringDefault: "Left,Top"Not in InspectorNot serialized

Edges kept at their authored distance when the parent resizes. Use a comma-separated combination of Left, Top, Right and Bottom; Dock overrides the effective anchor without deleting it.

`Dock`

StringDefault: "None"

Automatic placement within the parent: None, Left, Top, Right, Bottom or Fill. Dock overrides effective Anchor layout without deleting the stored anchors.

`Margin`

StringDefault: "0"

External spacing as one non-negative DIP value or Left,Top,Right,Bottom.

`Cursor`

StringDefault: "Default"

Pointer shown over the control: Default, Arrow, Hand, IBeam, Cross, Wait, Help, SizeAll, SizeNS, SizeWE, SizeNWSE, SizeNESW or NotAllowed.

`Opacity`

DoubleDefault: 1

Visual opacity from 0 (transparent) to 1 (opaque).

Range: 0 to 1.

`DesignLocked`

BooleanDefault: FalseDesigner only

Prevents movement and resizing in the Designer without changing runtime interaction.

`Visible`

BooleanDefault: True

Whether the control is shown in the running application.

`Enabled`

BooleanDefault: True

Whether the control accepts user interaction in the running application.

`HitTestVisible`

BooleanDefault: True

Whether the running control participates in pointer hit testing. The control remains selectable in the Designer.

`AllowDrop`

BooleanDefault: False

Whether this running control accepts application drag-and-drop operations; Designer movement is separate.

`DragMode`

LongDefault: 0

VB control drag: 0 Manual (code starts a drag with the Drag method) or 1 Automatic (a left-button press starts a drag, and the control raises no Click, MouseDown or MouseUp for that press).

Range: 0 to 1.

`DragIcon`

StringDefault: ""

Case-insensitive name of a declared project image resource shown under the pointer while this control is dragged; empty shows a grey outline of the control.

`Font`

StringDefault: ""

Font as Family|Size or Family|Size|Regular/Bold|Normal/Italic, size 6–96 DIP. Empty uses the theme font; System uses the theme family.

`ForeColor`

StringDefault: ""

Text color as #RRGGBB. Empty uses the current macOS theme color.

`BackColor`

StringDefault: ""

Background color as #RRGGBB. Empty uses the current macOS theme color.

`Padding`

StringDefault: "4"

Internal spacing around ListBox rows as one non-negative DIP value or Left,Top,Right,Bottom.

`BorderStyle`

StringDefault: "Solid"

ListBox border rendering: Solid or None.

`BorderColor`

StringDefault: ""

Border color as #RRGGBB. Empty uses the theme border color.

`BorderWidth`

DoubleDefault: 1

Uniform border width in device-independent points.

Range: 0 to 100.

`CornerRadius`

DoubleDefault: 0

Uniform ListBox corner radius in device-independent points.

Range: 0 to 1000.

`AccessibleName`

StringDefault: ""

Name announced by assistive technology. Empty uses the stable control Name.

`AccessibleDescription`

StringDefault: ""

Additional help text announced by assistive technology.

`AutomationId`

StringDefault: ""

Stable automation identifier; empty uses the component Name.

`AccessibleRole`

StringDefault: "Auto"

Accessibility role override. Auto preserves the native semantic role; explicit values use the corresponding platform automation role.

`ToolTipText`

StringDefault: ""

Help text shown when the pointer rests over the running control; empty disables the tooltip.

`Tag`

StringDefault: ""

Application-defined text associated with this control; McBasic™ does not interpret it.

`Items`

StringDefault: ""

Newline-separated display values; each non-empty line is one item in this bounded ListBox slice.

Designer starting value: "Item 1\nItem 2\nItem 3".

`DisplayMember`

StringDefault: ""

Column shown when BASIC binds a BindingSource; empty uses the first result column.

`ValueMember`

StringDefault: ""

Column returned by SelectedValue when bound; empty uses DisplayMember.

`SelectionMode`

StringDefault: "Single"

Selection behavior: Single, Multiple (independent toggle) or Extended (standard Command/Shift ranges).

`Sorted`

BooleanDefault: False

Sorts displayed items by deterministic case-insensitive ordinal text, with ordinal and source-order tie breakers.

`HorizontalScrollBar`

StringDefault: "Auto"

Horizontal scrollbar visibility: Auto, Visible, Hidden or Disabled.

`VerticalScrollBar`

StringDefault: "Auto"

Vertical scrollbar visibility: Auto, Visible, Hidden or Disabled.

`SelectedIndex`

LongDefault: -1

Zero-based selected item index, or -1 when no item is selected.

Range: -1 to 100000.

Designer starting value: 0.

`ListIndex`

LongDefault: -1Not in InspectorNot serialized

Run-time alias of SelectedIndex (VB6 name): zero-based, -1 for no selection.

Range: -1 to 100000.

`Index`

LongDefault: -1Read only in BASICDesigner Index row

Position of this control in its control array, 0 to 32767. Several controls share one name only when every one of them has an Index. Absent from the layout, and -1 in code, when the control is not in an array.

Designer values: 0 to 32767. Clear the dedicated Index row for a non-array control; BASIC then reads -1.

Events and parameters#

Replace control with the object’s Name when creating a handler. ByRef arguments may be changed by your handler; ByVal arguments report an input value.

SelectionChanged

Occurs once after the effective selection changes; assigning the same effective selection does not raise it.

Supported aliases: Change. Canonical name: SelectionChanged.