A tree-view control is a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and an optional bitmapped image, and each item can have a list of subitems associated with it. By clicking an item, the user can expand or collapse the associated list of subitems.
Styles
Every item in a tree-view control can have two images associated with it. An
item displays one image when it is selected and the other when it is not. To
include images with tree-view items, first use the Image Lists functions
to create an image list and add images to it. Then associate the image list with
the tree-view control by using the
The following example creates an image list, adds three bitmaps to the list, and associates the image list with a tree-view control.
// InitTreeViewImageLists - creates an image list, adds three bitmaps
// to it, and associates the image list with a tree-view control.
// Returns TRUE if successful, or FALSE otherwise.
// hwndTV - handle to the tree-view control.
//
// Global variables and constants
// g_nOpen, g_nClosed, and g_nDocument - integer variables for
// indexes of the images.
// CX_BITMAP and CY_BITMAP - width and height of an icon.
// NUM_BITMAPS - number of bitmaps to add to the image list.
BOOL InitTreeViewImageLists(HWND hwndTV)
{
HIMAGELIST himl; // handle to image list
HBITMAP hbmp; // handle to bitmap
// Create the image list.
if ((himl = ImageList_Create(CX_BITMAP,
CY_BITMAP,
FALSE,
NUM_BITMAPS, 0)) == NULL)
return FALSE;
// Add the open file, closed file, and document bitmaps.
hbmp = LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_OPEN_FILE));
g_nOpen = ImageList_Add(himl, hbmp, (HBITMAP)NULL);
DeleteObject(hbmp);
hbmp = LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_CLOSED_FILE));
g_nClosed = ImageList_Add(himl, hbmp, (HBITMAP)NULL);
DeleteObject(hbmp);
hbmp = LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_DOCUMENT));
g_nDocument = ImageList_Add(himl, hbmp, (HBITMAP)NULL);
DeleteObject(hbmp);
// Fail if not all of the images were added.
if (ImageList_GetImageCount(himl) < 3)
return FALSE;
// Associate the image list with the tree-view control.
TreeView_SetImageList(hwndTV, himl, TVSIL_NORMAL);
return TRUE;
}
You add an item to a tree-view control by sending the
The example in this section demonstrates how to create a table of contents based on the information in a text file. The example includes two functions. The first function searches a file for headings. When it finds one, it extracts the text of the heading and the value that indicates the level of the heading and then passes them to the second function.
The second function adds an item to a tree-view control, using the heading text as the item's label and the heading level to determine the parent item for the new item. A level one heading is added to the root of the tree-view control, a level two heading is added as a child item of the previous level one item, and so on. The function assigns an image to an item based on whether it has any child items. If an item has child items, it gets an image representing a closed folder. Otherwise, it gets an image representing a document. An item uses the same image for both the selected and nonselected states
// InitTreeViewItems - extracts headings from the specified file and
// passes them to a function that adds them to a tree-view control.
// Returns TRUE if successful, or FALSE otherwise.
// hwndTV - handle to the tree-view control.
// lpszFileName - name of file with headings.
BOOL InitTreeViewItems(HWND hwndTV, LPSTR lpszFileName)
{
HANDLE hf; // handle to file
char szItemText[128]; // label text of tree-view item
int nLevel; // heading level
// Open the file to parse.
if ((hf = CreateFile(lpszFileName,
GENERIC_READ,
FILE_SHARE_READ,
(LPSECURITY_ATTRIBUTES)NULL,
OPEN_EXISTING,
FILE_ATTRIBUTE_NORMAL,
(HANDLE)NULL)) == (HANDLE)INVALID_HANDLE_VALUE)
return FALSE;
// Call private function to parse the file looking for headings.
while (GetNextHeadingAndLevelFromFile(hf, szItemText, &nLevel))
// Add the item to the tree-view control.
AddItemToTree(hwndTV, szItemText, nLevel);
return TRUE;
}
// AddItemToTree - adds items to a tree-view control.
// Returns the handle to the newly added item.
// hwndTV - handle to the tree-view control.
// lpszItem - text of the item to add.
// nLevel - level at which to add the item.
HTREEITEM AddItemToTree(HWND hwndTV, LPSTR lpszItem, int nLevel)
{
TVITEM tvi;
TVINSERTSTRUCT tvins;
static HTREEITEM hPrev = (HTREEITEM)TVI_FIRST;
static HTREEITEM hPrevRootItem = NULL;
static HTREEITEM hPrevLev2Item = NULL;
HTREEITEM hti;
tvi.mask = TVIF_TEXT | TVIF_IMAGE
| TVIF_SELECTEDIMAGE | TVIF_PARAM;
// Set the text of the item.
tvi.pszText = lpszItem;
tvi.cchTextMax = sizeof(tvi.pszText)/sizeof(tvi.pszText[0]);
// Assume the item is not a parent item, so give it a
// document image.
tvi.iImage = g_nDocument;
tvi.iSelectedImage = g_nDocument;
// Save the heading level in the item's application-defined
// data area.
tvi.lParam = (LPARAM)nLevel;
tvins.item = tvi;
tvins.hInsertAfter = hPrev;
// Set the parent item based on the specified level.
if (nLevel == 1)
tvins.hParent = TVI_ROOT;
else if (nLevel == 2)
tvins.hParent = hPrevRootItem;
else
tvins.hParent = hPrevLev2Item;
// Add the item to the tree-view control.
hPrev = (HTREEITEM)SendMessage(hwndTV,
TVM_INSERTITEM,
0,
(LPARAM)(LPTVINSERTSTRUCT)&tvins);
// Save the handle to the item.
if (nLevel == 1)
hPrevRootItem = hPrev;
else if (nLevel == 2)
hPrevLev2Item = hPrev;
// The new item is a child item. Give the parent item a
// closed folder bitmap to indicate it now has child items.
if (nLevel > 1)
{
hti = TreeView_GetParent(hwndTV, hPrev);
tvi.mask = TVIF_IMAGE | TVIF_SELECTEDIMAGE;
tvi.hItem = hti;
tvi.iImage = g_nClosed;
tvi.iSelectedImage = g_nClosed;
TreeView_SetItem(hwndTV, &tvi);
}
return hPrev;
}