InsertListItem

int InsertListItem (int panelHandle, int controlID, int itemIndex, char itemLabel[], ...);

Purpose

Inserts a label/value pair into a list or ring 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.

Parameters

Input
Name Type Description
panelHandle integer Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID integer 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 NewCtrl or DuplicateCtrl.
itemIndex integer Zero-based index into the list where InsertListItem places the item. Pass –1 to insert the item at the end of the list.
itemLabel string 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);
InsertListItem (handle, ctrlID, 1, "Ford\033p100lProbe\033p200lBlack", 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);
InsertListItem (handle, cID, 1, "\033p32cFord\033p130cProbe\033p230cBlack", 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, the code is \033fgXXXXXX where XXXXXX is a 6-digit RGB value specified in hex.

To change the background color, 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, 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), embed the escape code \033m- in the itemLabel parameter.
itemValue depends on type of list control 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 integer Return value indicating whether the function was successful. A negative number indicates that an error occurred.

Code Error Message String
xx Success