117 lines
4.6 KiB
Text
117 lines
4.6 KiB
Text
# 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.
|
|
|
|
.section Widgets
|
|
.topic widget.combobox
|
|
.title ComboBox
|
|
.toc 0 ComboBox
|
|
.index ComboBox
|
|
.index wgtComboBox
|
|
.index wgtComboBoxSetItems
|
|
.index wgtComboBoxAddItem
|
|
.index wgtComboBoxRemoveItem
|
|
.index wgtComboBoxClear
|
|
.index wgtComboBoxGetSelected
|
|
.index wgtComboBoxSetSelected
|
|
|
|
.h2 ComboBox
|
|
|
|
A combination of a single-line text input and a drop-down list. The user can type a value or select one from the list. When the user picks a list item, its text is copied into the edit buffer. Supports full text editing (cursor movement, selection, clipboard, undo) via the texthelp library, and a popup overlay list via the listhelp library.
|
|
|
|
Depends on "texthelp" and "listhelp" helper libraries (declared in combobox.dep).
|
|
|
|
Header: widgets/comboBox.h
|
|
|
|
.h3 Creation
|
|
|
|
.code
|
|
WidgetT *cb = wgtComboBox(parent, 128);
|
|
wgtComboBoxAddItem(cb, "Arial");
|
|
wgtComboBoxAddItem(cb, "Courier");
|
|
wgtComboBoxAddItem(cb, "Times");
|
|
.endcode
|
|
|
|
.h3 API Functions
|
|
|
|
.table
|
|
Function Description
|
|
-------- -----------
|
|
WidgetT *wgtComboBox(parent, maxLen) Create a combo box. maxLen is the maximum editable text length (0 => default 256).
|
|
void wgtComboBoxSetItems(w, items, count) Set the dropdown items from a const char ** array. Items are not copied -- caller owns them.
|
|
int32_t wgtComboBoxGetSelected(w) Get the index of the last selected item (-1 if the text was typed freely).
|
|
void wgtComboBoxSetSelected(w, idx) Select an item by index. Copies its text into the edit buffer.
|
|
void wgtComboBoxAddItem(w, text) Append an item to the owned list (strdup'd).
|
|
void wgtComboBoxRemoveItem(w, idx) Remove an owned item by index.
|
|
void wgtComboBoxClear(w) Remove all owned items and reset the selection.
|
|
const char *wgtComboBoxGetItem(w, idx) Get the text of an item by index.
|
|
int32_t wgtComboBoxGetItemCount(w) Get the total number of items.
|
|
.endtable
|
|
|
|
.h3 API Struct (wgtRegisterApi "combobox")
|
|
|
|
.table
|
|
Slot Function
|
|
---- --------
|
|
create wgtComboBox
|
|
setItems wgtComboBoxSetItems
|
|
getSelected wgtComboBoxGetSelected
|
|
setSelected wgtComboBoxSetSelected
|
|
addItem wgtComboBoxAddItem
|
|
removeItem wgtComboBoxRemoveItem
|
|
clear wgtComboBoxClear
|
|
getItem wgtComboBoxGetItem
|
|
getItemCount wgtComboBoxGetItemCount
|
|
.endtable
|
|
|
|
.h3 Properties (BASIC Interface)
|
|
|
|
.table
|
|
Property Type Access Description
|
|
-------- ---- ------ -----------
|
|
ListIndex Integer Read/Write Index of the currently selected item (-1 if none).
|
|
.endtable
|
|
|
|
Editable text is accessible via the generic "Text" property. "ListCount" is available through the ListCount method.
|
|
|
|
.h3 Methods (BASIC Interface)
|
|
|
|
.table
|
|
Method Description
|
|
------ -----------
|
|
AddItem text$ Append an item to the dropdown list.
|
|
Clear Remove all items and clear the selection.
|
|
List(index%) Return the text of the item at the given index.
|
|
ListCount() Return the total number of items.
|
|
RemoveItem index% Remove the item at the given index.
|
|
.endtable
|
|
|
|
.h3 Events
|
|
|
|
.table
|
|
Callback Description
|
|
-------- -----------
|
|
onChange Fires when the selection or text changes.
|
|
.endtable
|
|
|
|
.h3 Default Event
|
|
|
|
"Click" (VB basName: ComboBox).
|