# List Controls

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) :
Copy

    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.
Copy

    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.
Copy

    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.
Copy

    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.
Copy

    function getCount(integer id)

Returns the number of items in the list.
Copy

    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.
Copy

    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.
Copy

    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.