# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.topic ctrl.listbox
.title ListBox
.toc 1 ListBox
.index ListBox
.index ListIndex
.index ListCount
.index AddItem
.index RemoveItem

.h1 ListBox

VB Equivalent: ListBox -- DVX Widget: listbox

A scrollable list of selectable items. Items are managed via methods (AddItem, RemoveItem, Clear). Supports single and multi-select modes, drag-to-reorder, and keyboard navigation with type-ahead search.

.h2 Type-Specific Properties

.table
  Property    Type      Description
  ---------   -------   -------------------------------------------
  ListIndex   Integer   Index of the currently selected item (-1 = no selection).
.endtable

.h2 Type-Specific Methods

.table
  Method            Parameters                                Description
  ---------------   ---------------------------------------   -------------------------------------------
  AddItem           Text As String                            Add an item to the end of the list.
  Clear             (none)                                    Remove all items from the list.
  ClearSelection    (none)                                    Deselect all items.
  IsItemSelected    Index As Integer                          Returns True if the item at Index is selected.
  List              Index As Integer                          Return the text of the item at the given index.
  ListCount         (none)                                    Return the number of items in the list.
  RemoveItem        Index As Integer                          Remove the item at the given index.
  SelectAll         (none)                                    Select all items (multi-select mode).
  SetItemSelected   Index As Integer, Selected As Boolean     Select or deselect a specific item.
  SetItems          Items As String                           Bulk-load items from a pipe-delimited string (e.g. "Red|Green|Blue"). Replaces existing items.
  SetMultiSelect    Multi As Boolean                          Enable or disable multi-select mode.
  SetReorderable    Reorderable As Boolean                    Enable or disable drag-to-reorder.
.endtable

Default Event: Click

.h2 Example

.code
Sub Form_Load ()
    List1.AddItem "Apple"
    List1.AddItem "Banana"
    List1.AddItem "Cherry"
End Sub

Sub List1_Click ()
    Dim idx As Integer
    idx = List1.ListIndex
    If idx >= 0 Then
        Label1.Caption = "Selected: " & List1.List(idx)
    End If
End Sub
.endcode

.link ctrl.common.props Common Properties, Events, and Methods
.link ctrl.combobox ComboBox
.link ctrl.dropdown DropDown
