Programming with List Box Controls
This topic describes how to complete the following tasks programmatically.
- Associating the data type of the list box control with values
- Associating an image with a list item
- Converting between label, value, and indices of items
- Creating a list box control
- Customizing the behavior of the list box
- Deleting and replacing items in the list box control
- Determining whether list items are checked
- Obtaining the number of items
- Obtaining the value and index of the currently selected item
- Setting the active item
Creating a List Box Control
Use NewCtrl to create a list box control. The list box control is empty initially. To insert items, call InsertListItem.
int listBoxCtrl;
listBoxCtrl = NewCtrl (panelHandle, CTRL_LIST_LS, "List Box", 40, 40);
InsertListItem (panelHandle, listBoxCtrl, 0, "First", 1);
InsertListItem (panelHandle, listBoxCtrl, 1, "Second", 2);
InsertListItem (panelHandle, listBoxCtrl, 2, "Third", 3);
Setting the Active Item
You can set the active item based on the list box index or the value of the list box item.
int val, index;
GetCtrlVal (panelHandle, PANEL_VAL, &val);
SetCtrlVal (panelHandle, PANEL_LISTBOX, val); // Based on value.
GetCtrlVal (panelHandle, PANEL_INDEX, &index);
SetCtrlIndex (panelHandle, PANEL_LISTBOX, index); // Based on index.
Deleting and Replacing Items in the List Box Control
Call DeleteListItem to delete a specified number of items from the list box control.
int numToDel, idxToDel;
GetCtrlVal (panelHandle, PANEL_IDXDELETE, &idxToDel);
GetCtrlVal (panelHandle, PANEL_NUMDEL, &numToDel);
DeleteListItem (panelHandle, PANEL_LISTBOX, idxToDel, numToDel);
Call ClearListCtrl to delete all of the items in the ring control.
ClearListCtrl (panelHandle, PANEL_LISTBOX);
Call ReplaceListItem to substitute one list item with another one you specify.
ReplaceListItem (panelHandle, PANEL_LISTBOX, 0, "Spectrum Analyzer", 1);
If you pass 0 to the itemLabel parameter, LabWindows/CVI uses the existing label.
Obtaining the Number of Items
int count;
GetNumListItems (panelHandle, PANEL_LISTBOX, &count);
Obtaining the Value and Index of the Currently Selected Item
int itemIndex, itemValue;
GetCtrlIndex (panelHandle, PANEL_LISTBOX, &itemIndex);
SetCtrlVal (panelHandle, PANEL_INDEX, itemIndex);
GetCtrlVal (panelHandle, PANEL_LISTBOX, &itemValue);
SetCtrlVal (panelHandle, PANEL_VALUE, itemValue);
Associating the Data Type of the Ring Control with Values
The data type for a list box control determines the type of data you can use for the value of list box items. You must match the values you pass to some of the functions with the data type of the control. The pointers you pass to functions that return values must also be compatible with the current data type of the control.
To set the data type, use the ATTR_DATA_TYPE attribute.
SetCtrlAttribute (panelHandle, PANEL_LISTBOX, ATTR_DATA_TYPE, VAL_STRING);
Because the data type of the values in the list box control is a character array in this instance, you must make sure the values you pass to the list box control and pointers to obtain values from the list box control are also string values.
InsertListItem (panelHandle, PANEL_LISTBOX, 0, "Int", "4 byte integer");
InsertListItem (panelHandle, PANEL_LISTBOX, -1, "Char", "Single byte character");
InsertListItem (panelHandle, PANEL_LISTBOX, -1, "Double", "8 byte floating point value");
InsertListItem (panelHandle, PANEL_LISTBOX, -1, "String", "Character array");
Converting between Label, Value, and Indices of Items
// Convert index to value.
int itemIndex, valLength;
char *itemValue = 0;
GetCtrlIndex (panelHandle, PANEL_LISTBOX, &itemIndex);
/* 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. */
GetValueLengthFromIndex (panelHandle, PANEL_LISTBOX, itemIndex, &valLength);
itemValue = malloc ((valLength + 1) * sizeof(char));
GetValueFromIndex (panelHandle, PANEL_LISTBOX, itemIndex, itemValue);
SetCtrlVal (panelHandle, PANEL_VALUE, itemValue);
// Convert index to label.
int labelLength;
char *label = 0;
GetLabelLengthFromIndex (panelHandle, PANEL_LISTBOX, itemIndex, &labelLength);
label = malloc ((labelLength + 1) * sizeof (char));
GetLabelFromIndex (panelHandle, PANEL_LISTBOX, itemIndex, label);
SetCtrlVal (panelHandle, PANEL_LABEL, label);
// Convert value to index.
int indexFromVal;
GetIndexFromValue (panelHandle, PANEL_LISTBOX, &indexFromVal, itemValue);
SetCtrlVal (panelHandle, PANEL_INDEX, indexFromVal);
Customizing the Behavior of the List Box
Use SetCtrlAttribute to customize the behavior of the list box control. For example, you can add a column for checkmarks to the list box and then customize how a user can check items.
SetCtrlAttribute (panelHandle, PANEL_LISTBOX, ATTR_CHECK_MODE, 1);
SetCtrlAttribute (panelHandle, PANEL_LISTBOX, ATTR_DRAGGABLE_MARKS, 1);
Associating an Image with a List Item
LabWindows/CVI includes predefined images that you can add to list items. Call the SetListItemImage to specify an image.
SetListItemImage (panelHandle, PANEL_LISTBOX, 0, VAL_FOLDER);
SetListItemImage (panelHandle, PANEL_LISTBOX, 1, VAL_OPEN_FOLDER);
SetListItemImage (panelHandle, PANEL_LISTBOX, 2, VAL_PLUS);
SetListItemImage (panelHandle, PANEL_LISTBOX, 3, VAL_CURRENT_FOLDER);
SetListItemImage (panelHandle, PANEL_LISTBOX, 4, VAL_MINUS);
SetListItemImage (panelHandle, PANEL_LISTBOX, 5, VAL_BLANK_IMAGE);
To get the value of the item associated with a list item, call GetListItemImage.
int itemImage;
GetListItemImage (panelHandle, PANEL_LISTBOX, 0, &itemImage);
Determining Whether List Items are Checked
If the list box has a column for checkmarks, you can use the IsListItemChecked, CheckListItem, and GetNumCheckedItems functions.
/* Verify if the first item of the list control is checked. */
int checked;
IsListItemChecked (panelHandle, PANEL_LISTBOX, 0, &checked);
/* Check the first item of a list box. */
CheckListItem (panelHandle, PANEL_LISTBOX, 0, 1);
/* Obtain the number of checked items. */
int totalChecked;
GetNumCheckedItems (panelHandle, PANEL_LISTBOX, &totalChecked);