ReplaceListItem
int ReplaceListItem (int panelHandle, int controlID, int itemIndex, char itemLabel[], ...);
Purpose
Replaces the label/value pair at a specific index in a list with a new label/value pair.
Supported Controls
You can use ReplaceListItem 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 the item is placed. |
| itemLabel | char [] | Label to associate with the new value. Pass 0 to use the existing label. 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 the empty string, LabWindows/CVI creates a placeholder for the image that you can fill using ReplaceListitem or SetImageBits. 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: ReplaceListItem (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: ReplaceListItem (handle, ctrlID, 0, "Chevrolet\033p100lCorvette\033p200lRed", 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), specify the escape code \033m- as the itemLabel parameter. The following code inserts a separator bar. InsertListItem (handle, ctrlID, 1, "\033m-", 1); The following code replaces a list item with a separator bar. InsertListItem (handle, ctrlID, 0, "Item1", 0); The first item in a list cannot be a separator bar. |
| itemValue | ... | Value to associate with the new label. 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
Example
Refer to userint\graphlegend.cws for an example of using the ReplaceListItem function.