InsertTreeItem
int InsertTreeItem (int panelHandle, int controlID, int relation, int relativeIndex, int position, char itemLabel[], char tagBase[], char tag[], ...);
Purpose
Inserts an item into the tree control. The new item position is defined by the relative index, the relation, and the position.
Inserting the new item causes the indices of existing items at and beyond the insertion point to increase by one.
The function returns the index of the new item or an error.
Supported Controls
You can use InsertTreeItem with tree 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. | ||
| relation | int |
Defines whether the new item will be a child or sibling of the relative item. This parameter is ignored if the tree is empty. You can use the following values: VAL_CHILD—The item is a child of the relative item. VAL_SIBLING—The item is a sibling of the relative item. |
||
| relativeIndex | int |
The index of the relative of the new item. The relation parameter defines whether the new item will be a child or sibling of the relative item. This parameter is ignored if the tree is empty. |
||
| position | int |
Defines the position of the new item. VAL_PREV—The new item is inserted before the relative item. Valid only for items inserted as a sibling. VAL_NEXT—The new item is inserted after the relative item. Valid only for items inserted as a sibling. VAL_FIRST—If the new item is inserted as a child, it is the first child of the relative index. If the new item is inserted as a sibling, it is the first sibling of the relative index. VAL_LAST—If the new item is inserted as a child, it is the last child of the relative index. If the new item is inserted as a sibling, it is the last sibling of the relative index. This parameter is ignored if the tree is empty.
|
||
| itemLabel | char [] | Label of the new tree item. | ||
| tagBase | char [] | Character string that InsertTreeItem uses to create a unique tag for the new item. If tagBase is NULL or empty, then InsertTreeItem creates a unique tag based on the label. If both tagBase and itemLabel are NULL or empty, then the generated tag will be TAG_1, TAG_2, and so on. |
||
| itemValue | ... | Value to associate with the new item. The data type must be the same as the data type of the control. | ||
| Output | ||||
| Name | Type | Description | ||
| tag | char [] | Unique tag associated with the new item. If tagBase is unique with respect to all the other tree item tags, then tag will be the same as tagBase. If InsertTreeItem has to generate a unique tag, then tag will be the generated character string. You can pass NULL if you do not want to get the tag. If tag is not NULL, the number of bytes in the buffer must be at least MAX_TREE_ITEM_TAG_LEN. |
||
Return Value
| Name | Type | Description |
| newItemIndex | int | Returns the index of the inserted item. Use the index to specify the tree item in subsequent function calls. Negative values indicate that an error occurred. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 7.0 and later
Examples
Refer to the following examples that use the InsertTreeItem function:
- apps\uirview\uirview.cws
Open example - userint\treeimage.cws
Open example