# 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.

## 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.
relation | integer | 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 | integer | 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 | integer | 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 | string | Label of the new tree item.
tagBase | string | 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 | depends on type of tree control | 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 | string | 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 | integer | 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.
Code | Error Message String
xx | Item Index (Success)