This general class of control comprises 2 basic groups - ListBox &
ComboBox. Now, a ListBox is just a list of text strings as you
would expect. A ComboBox comprises a ListBox AND an EditText
control combination, which explains the name. Programmatically,
the difference between each type of list is this: (i) A Listbox
can select multiple items if created with the appropriate flag/s.
(ii) A ComboBox's edit field allows access to it via
getText()& setText(). The Combox group includes 2 additional
kinds - ComboDropDownList & ComboDropDown. A
ComboDropDownList behaves exactly list a ListBox except that it
has the DropDown feature but no edit box. A ComboDropDown is a
ComboBox where the list part drops down. Due to the
shortsightedness of the powers that be, a list can only contain
32767 items. When an event occurs in a list it sends a
notification message to the dialog box procedure of the owner
window in the form of a WM_COMMAND message. At the creation of a
list control the style flags can be used to modify the
behaviour/appearance etc.. Please consult the API documentation
for more details. The control types ComboBox & ComboDropDown
have edit controls embedded within them. These edit controls are
subclassed and almost all messages are sent via the Combo's
handler.
Where a control has a fixed list, the list items may be selected
by using the usual navigation keys such as the arrow keys. Where
a control has a dropdown list (ComboDropDown or
ComboDropDownList) the list may be opened or closed by pressing
F4
or clicking the down facing chevron.
The following routines are used with Lists & Combos (NB: some
of these routines are heavily optimized; all of them are fast) :
function insertItem(integer id, sequence text, integer pos)
The new item will be inserted into the list at index pos. If pos
is 0 then the item will be appended to the list unless the list
has sort flags in which case the item will be inserted in it's
sort order. If text contains multiple text strings then they will
all be inserted into the list starting from the point specified;
sorted lists will put each item in sort order. The function will
return the index position of the last item inserted except for
sorted lists where 1 will be returned. If an error then 0 will be
returned.
procedure deleteItem(integer id, object pos)
The list item will be deleted. If pos is 0 then the entire list
will be erased. If pos is a sequence then it must be a 2 element
sequence which specifies the lower & upper boundaries
(inclusive) of a range of elements that will be deleted from the
list.
function getItem(integer id, object pos)
The list item's text will be retrieved. If the function fails
then an empty string will be returned. If pos is a sequence then
it must be a 2 element sequence which specifies the lower &
upper boundaries (inclusive) of a range of elements that will be
retrieved from the list. If pos = 0 then this function will
attempt to retrieve the currently selected item but will fail
(return "") if multiple items were selected.
procedure setItem(integer id, sequence text, integer pos)
The text of the item at index pos will be replaced by the new
string. A side-effect of the API calls within this routine is
that the list will be scrolled, if needed, so that the item at
the index position is visible in the display window.
function getCount(integer id)
Returns the number of items in the list.
function findItem(integer id, sequence text, integer pos)
An attempt is made to find the index of the list item where the
text matches the items prefix (ie, the list item's text can be
longer). The search will start from pos. If the search reaches
the end of the list it will loop back to the start and continue
until it meets pos again. If pos is 0 then the search will
commence from the start of the list. function getIndex(integer
id) Retrieves the list index currently selected. If the list is
capable of multiple selections and more than one item is selected
then a sequence containing the selected items is returned.
procedure setIndex(integer id, object selection)
Causes the list index to point to item selection. If selection is
0 then the list will be entirely de-selected. If the list is a
ListBox AND it was created with the LBS_MULTIPLESEL flag then:
(i) selection can be a sequence of indexes that will be
simultaneously selected. All previously selected items will first
be de-selected. (ii) If selection is -1 the whole list will be
selected.
procedure setTopItem(integer id, integer pos)
The list will be scrolled so that the position referenced appears
at the top of the display window. This does NOT mean that that
the topmost item displayed is now the current selection - you
must use setIndex() for that.