# 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.dropdown
.title DropDown
.toc 1 DropDown
.index DropDown

.h1 DropDown

DVX Extension -- DVX Widget: dropdown (non-editable drop-down list)

A read-only drop-down list. Unlike ComboBox, the user cannot type free text; they can only select from the provided items. Supports AddItem / RemoveItem / Clear / List. Use the arrow keys to navigate and Enter to commit when the list is open.

.h2 Type-Specific Properties

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

.h2 Type-Specific Methods

.table
  Method              Description
  ------              -----------
  AddItem text$       Append an item to the drop-down list.
  Clear               Remove all items.
  List(index%)        Return the text of the item at the given index.
  ListCount()         Return the number of items in the list.
  RemoveItem index%   Remove the item at the given index.
.endtable

Default Event: Click

.h2 Example

.code
Begin DropDown DropDown1
End

Sub Form_Load ()
    DropDown1.AddItem "Small"
    DropDown1.AddItem "Medium"
    DropDown1.AddItem "Large"
    DropDown1.ListIndex = 1
End Sub

Sub DropDown1_Click ()
    Label1.Caption = "Picked: " & DropDown1.List(DropDown1.ListIndex)
End Sub
.endcode

.link ctrl.common.props Common Properties, Events, and Methods
.link ctrl.listbox See ListBox for details