# Programming with List Box Controls

List box controls contain an indexed set of label/value pairs. Labels are strings that appear on the list box, and values can be of any type.

Use SetCtrlVal to set the active item of a list box control to the first of its items that matches a given value. Use SetCtrlIndex to set the active item based on a given zero-based index.

GetNumListItems obtains the number of items contained in a list control. ClearListCtrl clears the contents of a list box control.

InsertListItem, ReplaceListItem and DeleteListItem operate on individual items.

GetValueFromIndex, GetIndexFromValue and GetLabelFromIndex allow you to convert between labels, values and indices.

Use GetCtrlVal to obtain the value of the currently selected list box item. Use GetCtrlIndex to obtain the zero-based index of the currently active item.

A list box control has a data type associated with it, so you must be careful to match the values you pass to some of the functions above with the data type of the control. The pointers you pass to functions which return values must also be compatible with the current data type of the control.

If the data type of the list box is VAL_STRING, then use GetValueLengthFromIndex to determine the size of the buffer needed to get the value strings. Keep in mind that the functions which return values append a NULL byte to the end of the text string, so you must make the buffer 1 byte larger than the value obtained from GetValueLengthFromIndex.

If the list box is in check mode, you can use the IsListItemChecked, CheckListItem and GetNumCheckedItems functions.

You can associate an image with a particular list item with SetListItemImage. GetListItemImage obtains the image associated with a particular list item.