InsertListItem
int InsertListItem (int panelHandle, int controlID, int itemIndex, char itemLabel[], ...);
Purpose
Inserts a label/value pair into a control at a specific zero-based index.
Inserting the new pair causes the indices of existing label/value pairs at and beyond the insertion point to increase by one.
You can create columns in a list box control by embedding escape codes in the itemLabel parameter.
Supported Controls
You can use InsertListItem with the following controls:
Parameters
| Input | ||
| Name | Type | Description |
| panelHandle | int | Specifier for a particular panel that is currently in memory. You can obtain this handle from functions such as LoadPanel and NewPanel. |
| controlID | int | The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by functions such as NewCtrl and DuplicateCtrl. |
| itemIndex | int | Zero-based index into the list where InsertListItem places the item. Pass –1 to insert the item at the end of the list. |
| itemLabel | char [] | Label to associate with itemValue. For picture rings, the label is actually an image, and you pass the pathname of the image as the itemLabel parameter. The image pathname can be a complete pathname or a simple filename. For simple filenames, the image file must be in the directory of the executable. If you pass NULL or an empty string, LabWindows/CVI creates a placeholder for the image that you can fill using ReplaceListitem, NewBitmapEx, or SetCtrlBitmap. You can create columns in a list box control by embedding escape codes in the itemLabel parameter. Use \033 to indicate an escape code, followed by p (for pixel), followed by a justification code of l (left), c (center), or r (right). For example, the following code sets a left-justified column at the 100- and 200-pixel positions: InsertListItem (handle, ctrlID, 0, "Chevrolet\033p100lCorvette\033p200lRed", 0); In the following example, the code segment sets a centered column at the 32-, 130-, and 230-pixel positions: InsertListItem (handle, ctrlID, 0, "\033p32cChevrolet\033p130cCorvette\033p230cRed", 0); To insert a vertical line at the current position in the label, the code is \033vline. You also can use escape codes to change the foreground and background colors of characters in a list box. The escape codes affect only the label in which they are embedded. The new color affects subsequent characters in the label until you change the color again or until you reach the end of the line.To change the foreground color for a list box control, the code is \033fgXXXXXX where XXXXXX is a 6-digit RGB value specified in hex. To change the background color for a list box control, the code is \033bgXXXXXX where XXXXXX is a 6-digit RGB value specified in hex. To restore either color to the default color for the text of a list box control, insert default instead of the 6-digit RGB value. To insert a separator bar into a ring control (ring, menu ring, recessed menu ring, or pop-up menu ring), specify the escape code \033m- as the itemLabel parameter. The following code inserts a separator bar between two items. InsertListItem (handle, ctrlID, 0, "Item1", 0); The first item in a list cannot be a separator bar. |
| itemValue | ... | Value to associate with itemLabel. The data type must be the same as the data type of the control. |
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful. A negative number indicates that an error occurred. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 3.0 and later
Examples
Refer to the following examples that use the InsertListItem function:
- toolbox\XMLSample.cws
Open example - userint\GraphAnnotations.cws
Open example - userint\GraphZooming.cws
Open example - userint\imagedit.cws
Open example - userint\listbox.cws
Open example - userint\Tooltips.cws
Open example - userint\treecopy.cws
Open example