typedef void (*ControlFunc) (Control *c);
Control *new_list_box(Window *w, Rect r, char *list[],
ControlFunc fn);
Control *add_list_box(Control *c, Rect r, char *list[],
ControlFunc fn);
int get_list_box_item(Control *c);
void set_list_box_item(Control *c, int index);
void change_list_box(Control *c, char **list);
void reset_list_box(Control *c);
The new_list_box function creates a list box, which displays lines of text from a NULL-terminated array of strings in a scrollable area on screen. Only one line of text can be selected at any one time.
Whenever the user clicks on one of the text strings with the mouse, that string becomes selected (is drawn highlighted) and the call-back function fn is called. The list box control is passed as a parameter, and its value field specifies which string was selected. Any previous selection is deselected first.
The add_list_box function works in the same way as new_list_box, except that it attaches the list box to a control rather than directly to a window.
The get_list_box_item function returns which item is selected or -1 if none are selected. Selected values range from zero to the number of strings minus one. The value will be -1 if no string is currently selected.
Which string is currently selected in the list box can be changed using the set_list_box_item function. This will change the hilighting to reflect the new selected item. Passing -1 to this function will remove all hilighting.
The change_list_box function sets a new array of strings to use in the list box, and redraws the list. The list of strings is copied, so modification or deletion of the passed-in list is possible without affecting the list box. The existing selection and scroll bar positions are retained if possible.
The reset_list_box function removes the selection highlighting (if any) and positions the scroll bars of the list box so that the first element is visible.