# Programming with Tree Controls

## Adding Tree Items and Columns

To insert a tree item, use InsertTreeItem. The tree control has a default item. New tree items inherit attributes from the default item. The default item is not visible. To set the value of the attributes of the default item, use SetTreeItemAttribute with VAL_DFLT_FOR_NEW_OBJECTS for the index parameter.

To insert columns, use InsertTreeColumn. Each column has a default cell, which is not visible. Cell attributes of new items are inherited from the default cell of each column. To set the value of the attributes of the default cell of a column, use SetTreeCellAttribute with VAL_DFLT_FOR_NEW_OBJECTS for the index parameter. The attribute values of new columns are initialized from the values of the attributes of the first column. The default cell of the new column is initialized from the default cell of the first column.

## Setting Tree Attributes

You can customize the appearance and behavior of the tree control. Use SetCtrlAttribute to set tree attributes, including attributes to show connection lines, show checkboxes or radio buttons, set the tree background color, enable drag and drop, and enable tooltips.

## Getting/Setting Tree Item Attributes

You can set attributes for tree items using SetTreeItemAttribute. Examples of tree item attributes that you can set include attributes that determine whether a user can edit a tree item label, whether an item expanded or collapsed, and what the tree item label color is. You also can use MakeTreeItemVisible to expand all the ancestors of an item and scroll the item into view. You can set an attribute for all tree items with SetTreeItemAttribute and VAL_ALL_OBJECTS for the index parameter.

To obtain the value of a tree item attribute, call GetTreeItemAttribute.

## Getting/Setting Tree Cell Attributes

To set tree cell attributes, use SetTreeCellAttribute. Cell attributes you can set include those to customize the appearance of tree cell labels. You can set an attribute for all tree cells with SetTreeCellAttribute and VAL_ALL_OBJECTS for the index and column index parameters.

To obtain the value of a tree cell attribute, call GetTreeCellAttribute.

## Getting/Setting Tree Column Attributes

Use SetTreeColumnAttribute to customize tree columns. You can use SetColumnWidthToWidestCellContents to make the width of the column as wide as the widest tree cell label. To set an attribute for all tree columns, use SetTreeColumnAttribute with VAL_ALL_OBJECTS for the column index parameter. To remove a column, call DeleteTreeColumn.

To obtain the value of a tree column attribute, call GetTreeColumnAttribute.

## Adding Images

The tree control maintains a list of images. You can add images to that list with AddTreeImage. To associate an image with a tree item, you can set the ATTR_IMAGE_INDEX and ATTR_COLLAPSED_IMAGE_INDEX of the item to the image index returned by AddTreeImage. If you want to use images other than the plus and minus icons for expanded and collapsed items, set the tree attributes ATTR_EXPANDED_IMAGE_INDEX and ATTR_COLLAPSED_IMAGE_INDEX with SetCtrlAttribute.

## Searching

To search for items in the tree, you can call GetTreeItem, GetTreeItemFromLabel, and GetTreeItemFromValue. These functions allow you to search for items that are related to a specified item. For example, you can search through all the children, descendents, or ancestors of a particular item. You can start your search from a beginning index and specify the direction to search. You can further narrow the search by specifying the state of the item to search. Item states include selected, exposed, marked, and expanded. To combine states, OR the state criteria flags. Use GetTreeItemFromTag to search for an item with the unique tag that you specify.

## Finding the Root of a Tree Item

The root of a tree item is the first-level ancestor. Pass VAL_ANCESTOR, VAL_LAST, and VAL_NEXT_PLUS_SELF to GetTreeItem as the relation, begin index, and direction parameters, respectively, to find the root item of a specified item. If GetTreeItem returns –1 in this case, the begin index is the root item.

## Sorting Tree Items

To sort tree items, call SortTreeItems. The default sort method is a case-sensitive comparison of the tree item labels. If you want to customize the search, pass your own comparison function. You can specify the column by which to sort the items, whether the sort is ascending or descending, and whether to sort the subtrees.

## Copying Tree Items

Use CopyTreeItem to copy tree items within the same tree or to a different tree. This function also copies the descendents of the tree item.

## Moving Items within Trees

Use MoveTreeItem to move an item and all its descendents to a new position in the tree.

## Setting the Active Item

If the tree selection mode is VAL_SELECTION_NONE or VAL_SELECTION_SINGLE, SetCtrlIndex and SetActiveTreeItem have the same behavior. When the selection mode is VAL_SELECTION_MULTIPLE, use SetActiveTreeItem and the selection effect parameter to specify the resulting selection. For example, to mimic the selection behavior of an interactive <Shift> and mouse click behavior, pass VAL_ADD_INTERVAL_TO_SELECTION to select all exposed items between the old active item and the specified new active item.

## Customizing the Context Menu

To customize the tree control context menu, insert menu items corresponding to tools you want to make available to the user. Specify a callback function and an item label using NewCtrlMenuItem. Whenever the menu item is selected, LabWindows/CVI calls the corresponding callback function.

In addition to inserting your own menu items, you can remove the built-in items included by default (Goto, Find, and Sort). Use HideBuiltInCtrlMenuItem and ShowBuiltInCtrlMenuItem to control the visibility of these items.

You also can use control menu attributes to configure context menus. Call GetCtrlMenuAttribute and SetCtrlMenuAttribute to get and set these attributes.

## Getting the Tree Index from a Screen Point

You can pass a screen point to GetIndexFromPoint to find the tree item, area, and column that contains that point.

## Other

A tree control has a data type associated with it, so you must be careful to match the values you pass to some of the preceding functions with the data type of the control. The pointers you pass to functions that return values must also be compatible with the current data type of the control.

In addition to specific tree control functions, you also can use all of the list box control functions. Some of the list box control functions, such as GetNumListItems and InsertListItem, are equivalent to the tree control functions but are simpler to use. Others, such as DeleteListItem and ReplaceListItem have no tree control function equivalent, and you must use the list box functions.